<!DOCTYPE html>
<html>
 <head>
  <title>
   Configuring PixieApp Routes
  </title>
  <meta content="&#xA9;Copyright IBM Corporation 2018" name="copyright"/>
  <meta content="&#xA9;Copyright IBM Corporation 2018" name="DC.Rights.Owner"/>
  <meta content="&#xA9; Copyright IBM Corporation 2016, 2017, 2018" name="dcterms.rights"/>
  <meta content="2018-03-09" name="DC.date"/>
 </head>
 <body>
  <div>
   <h1>
    Configuring PixieApp Routes
   </h1>
   <div>
    <h1>
     @PixieApp
    </h1>
    <p>
     Python class annotation to denote that a class is a PixieApp.
    </p>
   </div>
   <div>
    <h1>
     @route
    </h1>
    <p>
     Python method annotation to denote that a method is a view. The contract is that when a method is annotated as a route, it must provide an HTML fragment for the framework to display.
    </p>
    <p>
     The default view must have a route with no arguments e.g.
     <cite>
      @route()
     </cite>
     . Any other route can have multiple key-value pairs, e.g.,
     <code>
      <span>
       @route(clicked="true",
      </span>
      <span>
       state1="foo")
      </span>
     </code>
     . When executing a kernel request, the PixieApp dispatcher will try to find the best view match based on its route arguments according to the following rules:
    </p>
    <ul>
     <li>
      <p>
       The routes with the most arguments are always evaluated first.
      </p>
     </li>
     <li>
      <p>
       All arguments must match for a route to be selected.
      </p>
     </li>
     <li>
      <p>
       If the route is not found, then the default route is selected.
      </p>
     </li>
     <li>
      <p>
       Each key of the route arguments can be either a transient state (options passed for the duration of the request) or persisted (field of the PixieApp class that remains present until explicitly changed).
      </p>
     </li>
    </ul>
    <p>
     <strong>
      Contract for the method defined as a view:
     </strong>
    </p>
    <ol>
     <li>
      <p>
       The method must provide an HTML fragment that can contain Jinja2 templating constructs (see
       <a href="http://jinja.pocoo.org/docs/dev/templates/">
        http://jinja.pocoo.org/docs/dev/templates/
       </a>
       for more details on Jinja2 templating).
      </p>
     </li>
     <li>
      <p>
       Optional: the method can have arguments that match the name of the route argument. This is useful when the route has wildcards for a particular state, and you want to use the value of this state in your code. For example:
      </p>
     </li>
    </ol>
    <pre>@route(state1="*", state2="*")
def myView(self, state1, state2):
    return "&lt;div&gt;state1 is {}&lt;/div&gt;&lt;div&gt;state2 is {}&lt;/div&gt;".format(state1, state2)</pre>
    <p>
     There are two ways of supplying these fragments:
    </p>
    <ol>
     <li>
      <p>
       Simply return a static string with the HTML fragment.
      </p>
     </li>
     <li>
      <p>
       Use either
       <code>
        self._addHTMLTemplate
       </code>
       or
       <code>
        self._addHTMLTemplateString
       </code>
       . Use one of these methods when you want to pass custom arguments to the Jinja2 template interpreter.
      </p>
     </li>
    </ol>
    <blockquote>
     <strong>
      Note
     </strong>
     <p>
      passing custom arguments to Jinja2 is an advanced feature that is rarely needed.
     </p>
    </blockquote>
   </div>
   <p>
    <h3>
     Return to main topic for:
    </h3>
    <ul>
     <li>
      <a href="pixieapps.html">
       PixieApps: Use PixieDust to Generate UI Elements
      </a>
     </li>
    </ul>
   </p>
  </div>
 </body>
</html>
